Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Added support for DynamoDbAutoGeneratedKey annotation #6373

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
anasatirbasa wants to merge 8 commits into aws:master
base: master
Choose a base branch
Loading
from anasatirbasa:feature/define-dynamo-db-autogenerated-key-annotation

Conversation

@anasatirbasa
Copy link
Contributor

@anasatirbasa anasatirbasa commented Aug 26, 2025 •
edited
Loading

Description

Added the facility of using an annotation that will auto-generate a key for an attribute in a class,
similar to the legacy V1 @DynamoDBAutoGeneratedKey, now ported and adapted for V2 with the Enhanced Client.

Important Restriction

This annotation is only valid for primary keys (PK/SK) or secondary index keys (GSI/LSI PK/SK).
If applied to a non-key attribute, the extension will throw an IllegalArgumentException.

If the attribute is not provided by the client, the SDK will automatically generate a value (UUID by default)
during serialization. If the attribute already has a value, it will be preserved depending on the update policy applied.
The implementation reuses the concept from V1 but leverages the V2 Enhanced Client extension model to achieve parity.

A key aspect of this feature is its combination with @DynamoDbUpdateBehavior for secondary index keys only. This determines whether a generated key is one-time only or is regenerated on every update:

  • Default (WRITE_ALWAYS) → The attribute will be regenerated on every write if missing, even during updates. Useful for attributes like lastUpdatedKey that are meant to refresh often.
  • WRITE_IF_NOT_EXISTS → The attribute will only be generated once (on the first insert) and preserved across updates. This is the recommended option for stable identifiers like createdKey.

Motivation and Context

#5497

This functionality was present in V1 under @DynamoDBAutoGeneratedKey. Many users requested its reintroduction in V2.
By introducing this annotation and the supporting extension, we align the Enhanced Client API with developer expectations and provide a familiar migration path.

Modifications

  • Added the new annotation @DynamoDbAutoGeneratedKey in the software.amazon.awssdk.enhanced.dynamodb.extensions.annotations package.
  • Introduced AutoGeneratedKeyExtension, which ensures attributes annotated with @DynamoDbAutoGeneratedKey are populated with a UUID when absent. This uses UUID.randomUUID() under the hood.
  • Added AutoGeneratedKeyTag as the annotation tag integration point.
  • Integrated with @DynamoDbUpdateBehavior to support both stable one-time keys - works for secondary index keys only (WRITE_IF_NOT_EXISTS) and regenerating keys (WRITE_ALWAYS).
  • Validated attribute type constraints (only String is supported).
  • Enforced placement rules (only PK/SK, LSI/GSI keys are allowed).
  • Added corresponding unit tests (AutoGeneratedKeyExtensionTest) and functional integration tests (AutoGeneratedKeyRecordTest) to verify correct behavior with real DynamoDB operations.
  • Tests validate multiple scenarios, including updates, conditional writes, composite annotations,
    and integration with VersionedRecordExtension.

Testing

The changes have already been tested by running the existing tests and also added new unit/integration tests
for the new flow, ensuring parity with V1 behavior while also validating V2-specific integration points.

Test Coverage Checklist

Scenario Done Comments if Not Done
1. Different TableSchema Creation Methods
a. TableSchema.fromBean(Customer.class) [x]
b. TableSchema.fromImmutableClass(Customer.class) for immutable classes [x]
c. TableSchema.documentSchemaBuilder().build() [ ]
d. StaticTableSchema.builder(Customer.class) [x]
2. Nesting of Different TableSchema Types
a. @DynamoDbBean with annotated auto-generated key [x]
b. @DynamoDbImmutable with annotated auto-generated key [x]
c. Auto-generated key combined with partition/sort key [x]
3. CRUD Operations
a. scan() [ ]
b. query() [x]
c. updateItem() preserves existing value or generates when absent [x]
d. putItem() with no key set (auto-generation occurs) [x]
e. putItem() with key set manually [x]
f. getItem() retrieves auto-generated key [x]
g. deleteItem() [ ]
h. batchGetItem() [ ]
i. batchWriteItem() [ ]
j. transactGetItems() [ ]
k. transactWriteItems() [ ]
4. Data Types and Null Handling
a. Annotated attribute is null → key auto-generated [x]
b. Annotated attribute non-null → value preserved [x]
c. Validation rejects non-String annotated attribute [x]
5. AsyncTable and SyncTable
a. DynamoDbAsyncTable Testing [x]
b. DynamoDbTable Testing [x]
6. New/Modification in Extensions
a. Works with other extensions like VersionedRecordExtension [x]
b. Test with Default Values in Annotations [ ]
c. Combination of Annotation and Builder passes extension [ ]
7. New/Modification in Converters
a. Tables with Scenario in ScenarioSl No.1 (All table schemas are Must) [ ]
b. Test with Default Values in Annotations [ ]
c. Test All Scenarios from 1 to 5 [ ]

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)

Checklist

  • I have read the CONTRIBUTING document
  • Local run of mvn install succeeds
  • My code follows the code style of this project
  • My change requires a change to the Javadoc documentation
  • I have updated the Javadoc documentation accordingly
  • I have added tests to cover my changes
  • All new and existing tests passed
  • I have added a changelog entry. Adding a new entry must be accomplished by running the scripts/new-change script and following the instructions. Commit the new file created by the script in .changes/next-release with your changes.
  • My change is to implement 1.11 parity feature and I have updated LaunchChangelog

License

  • I confirm that this pull request can be released under the Apache 2 license

@anasatirbasa anasatirbasa requested a review from a team as a code owner August 26, 2025 06:36
@anasatirbasa anasatirbasa force-pushed the feature/define-dynamo-db-autogenerated-key-annotation branch 2 times, most recently from 519acfe to fa35bfc Compare August 26, 2025 11:31
@anasatirbasa anasatirbasa force-pushed the feature/define-dynamo-db-autogenerated-key-annotation branch from 586dbf5 to 1c0b19f Compare August 27, 2025 17:07
@anasatirbasa anasatirbasa force-pushed the feature/define-dynamo-db-autogenerated-key-annotation branch 4 times, most recently from 335e532 to f3a3ad1 Compare August 28, 2025 06:20
@anasatirbasa anasatirbasa force-pushed the feature/define-dynamo-db-autogenerated-key-annotation branch 2 times, most recently from d407b73 to e2b74e3 Compare September 5, 2025 07:51
@anasatirbasa anasatirbasa force-pushed the feature/define-dynamo-db-autogenerated-key-annotation branch from fb82197 to ede74c8 Compare September 5, 2025 14:07
Copy link

@marcusvoltolim marcusvoltolim left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No tests with @DynamoDbSortKey

Copy link

marcusvoltolim commented Sep 16, 2025 •
edited
Loading

This solution still doesn't work for PartitionKey or SortKey, because UpdateBehavior are not applied to either as shown in the print below.

This is a workaround because it doesn't generate new values ​​in primaryKeys because the new extension validates if the value is missing, but it doesn't solve the root problem. Therefore, each new extension that can be applied to a PK must address this issue. The best approach is to not pass PKs to WriteModification.

image

Copy link
Contributor Author

Hello @marcusvoltolim,

Thank you very much for your review.

I have added tests for @DynamoDbSortKey as you suggested. The test class (AutoGeneratedKeyRecordTest) now covers all 4 supported key types with @DynamoDbAutoGeneratedKey:

  • Primary partition key (@DynamoDbPartitionKey)
  • Primary sort key (@DynamoDbSortKey)
  • GSI partition key (@DynamoDbSecondaryPartitionKey)
  • GSI sort key (@DynamoDbSecondarySortKey)

Regarding your comment about @DynamoDbUpdateBehavior: You're absolutely correct. Based on the implementation, the @DynamoDbAutoGeneratedKey annotation works with @DynamoDbUpdateBehavior only for secondary index keys (GSI/LSI partition and sort keys). For primary keys (both partition and sort), UpdateBehavior has no effect since primary keys cannot be null in DynamoDB and are always required for update operations.

I have updated the tests, ticket description, and PR description to clearly reflect this.

Could you please take another look when you have a chance? Thank you!

Copy link
Contributor

Hi @anasatirbasa ,

I read through the PR, I have a few concerns I wanted to raise with the entire team before providing feedback. Will update you soon.

Copy link
Contributor

RanVaknin commented Oct 28, 2025 •
edited
Loading

Hi @anasatirbasa, thanks for the wait.

I have reviewed this PR with the team and have a few points that we would ideally like to fix.

I agree that introducing this separate annotation would solve the problem in an "opt in" non invasive way.

Considerations:

  1. I'm trying to verify is whether the following is correct:

If both @DynamoDbAutoGeneratedUuid and @DynamoDbAutoGeneratedKey are applied to the same field, both extensions will execute in chain order. Since AutoGeneratedKeyExtension checks for existing values before generating, the behavior depends on registration order:

  • If AutoGeneratedUuidExtension (current) runs first: It generates a UUID, then AutoGeneratedKeyExtension (new) sees the value exists and skips generation
  • If AutoGeneratedKeyExtension (current) runs first: It generates conditionally, then AutoGeneratedUuidExtension (old) overwrites it anyway

This creates unpredictable behavior. If this is the case, can we please add some tests that cover it, and throw an exception when both annotations (new and current) are applied to the same field?

  1. Fix documentation for WRITE_IF_NOT_EXISTS:

In v1, @DynamoDBAutoGeneratedKey used DynamoDBAutoGenerateStrategy.CREATE, which only generated UUIDs when the annotated value was null.
The v2 Enhanced Client’s @DynamoDbAutoGeneratedUuid removed this conditional logic entirely - it always generates regardless of existing values. The javadoc documents this as intentional:

"Every time a record with this attribute is written to the database it will update the attribute with a UUID#randomUUID string."

but also, misleadingly suggests using UpdateBehavior.WRITE_IF_NOT_EXISTS as a workaround, which doesn’t work for primary keys due to DynamoDB’s updateItem API not allowing conditional updates on primary key attributes.

We will likely ask you to add more test coverage similar to other extensions test coverage, but I will provide more concrete about testing gaps in the near future after another review.

Thanks,
Ran~

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer

@marcusvoltolim marcusvoltolim marcusvoltolim requested changes

Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

AltStyle によって変換されたページ (->オリジナル) /